home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / utilit~1 / gemtrm12.zoo / gemterm.doc < prev    next >
Encoding:
Text File  |  1992-11-08  |  15.7 KB  |  348 lines
  1. ---------------------------------------------------------------------------
  2.  
  3.                 Gemterm V1.2
  4.         
  5.  
  6.              Freeware from Martin Gergeleit (1992)
  7.  
  8. ---------------------------------------------------------------------------
  9.  
  10. Intro
  11.  
  12. This is Gemterm, a xterm-clone for GEM plus MiNT. If you know MiNT, you
  13. probably know BG.ACC or TOSWIN. Gemterm does the similar things, but it is
  14. optimized for the use together with the Gemini desktop replacement. This
  15. means:
  16.  
  17. - Gemterm provides virtual vt52 windows with concurrent TOS programs running 
  18.   inside. The number of windows is only limited by memory and/or the TOS
  19.   version since V1.2.
  20.  
  21. - Gemterm is an Accessory, that should run concurrently with any "clean" GEM
  22.   program. It also runs as PRG since V1.2.
  23.  
  24. - Gemterm supports the Gemini VA-protocol, so that dragging of objects into
  25.   Gemterm-windows results in inserting the objects name as text, as known from
  26.   the Gemini-console.
  27.  
  28. - Gemterm uses GDOS fonts.
  29.  
  30. - Gemterm provides a scroll-back buffer and allows for cut-and-paste of text 
  31.   between Gemterm-windows.
  32.  
  33. - Gemterm-windows may be defined to be persistent. This means a window will
  34.   resist a change of the main GEM PRG without the need to reopen it by hand.
  35.   
  36. - Gemterm can save its status into a configuration file and will reboot to
  37.   the saved configuration. It will also start up again the TOS programs inside
  38.   its windows. Gemterm also supoorts the TOSRUN pipe. The small programm
  39.   "gxterm.ttp" (included in the Gemterm distribution) allows the startup of a
  40.   new window from within a TOS program.
  41.   
  42. - Gemterm also serves as a (very) basic terminal program.
  43.  
  44. - Gemterm claims to be "clean" itself.
  45.  
  46. - Gemterm comes with sources and it is free.
  47.  
  48. BUT:
  49.  
  50.  GEMTERM COMES WITH ABSOLUTELY NO WARRANTY, NOR WILL I BE LIABLE FOR ANY
  51.  DAMAGES INCURRED FROM THE USE OF IT. USE ENTIRELY AT YOUR OWN RISK!!!
  52.  
  53. Gemterm has not been tested very much so far. I used it myself during the
  54. development and I tested it with some GEM PRGs. It runs on my machine, a
  55. 260ST (yes, they still exist even in the age of the falcon) + 2.5 MB, a 
  56. monochrome SM124 (I is reported to run also on a color screen), TOS 1.04,
  57. MiNT 0.95, and Gemini 1.21. Gemterm should run on any ST on any TOS, 
  58. but I have not tested it on any machine other than mine.
  59. I will try to do any sensible bugfix, but I will not support any fancy speed up
  60. extensions (Hard- or Software) nor any other ST models or TOS version, as I 
  61. have no access to any TT, STE or Falcon. 
  62.  
  63. On the other hand: Gemterm comes with the complete sources (even if comments 
  64. are rare and the code is not very pretty). It is compiled with gcc 1.40 and 
  65. mintlib Patchlevel 20, so if you suggest any enhancements: Try it!
  66.  
  67. ---------------------------------------------------------------------------
  68.  
  69. What is new since V1.0
  70.  
  71. - Gemterm now checks wether GDOS is loaded or not. V1.0 crashed if there was no
  72.   GDOS.
  73. - The font selector now knows about the number of fonts installed. This should 
  74.   correct a bug that disabled font selection in some cases.
  75.  
  76. What is new since V1.1
  77.  
  78. - Gemterm now runs also as application.
  79. - Gemterm now supports the TOSRUN pipe.
  80. - The current working directory is now also a parameter for a program that
  81.   should be launched in a window.
  82. - Gemterm now knows about the environment variables "GEMTERMINF", "GEMTERMTTY", 
  83.   "GEMTERMAPPL" and "GEMTERMWINS". "GEMTERMINF" sets the path and the filename 
  84.   of the configuration file. "GEMTERMTTY" selects the device that is 
  85.   connected to the tty window. "GEMTERMAPPL" denotes the main application that
  86.   Gemterm wants to talk to via the VA protocol and "GEMTERMWINS" adjusts the
  87.   maximum number of term window during startup.
  88. - Gemterm reads the environment variables "SHELL" and "HOME" for its default
  89.   configuration.
  90. - Bug-reports should be much easier, if you recompile Gemterm with the -DDEBUG
  91.   option in case of crashes. With this option Gemterm traces all its actions to
  92.   stderr.
  93. - A bug that hang GEM, when activating window-arrows with a very high 
  94.   frequentcy should be fixed. (No more additional WM_REDRAW message from 
  95.   Gemterm to itself, but instant redrawing.)
  96.  
  97.  
  98. ---------------------------------------------------------------------------
  99.  
  100. How to install Gemterm
  101.  
  102. Simply copy GEMTERM.ACC into the root directory of you boot-partition (floppy?)
  103. and make sure that MiNT is installed as well. Reboot the machine. The entry
  104. "Gemterm" should appear in the GEM menu bar. If you want to use Gemterm as 
  105. an application (PRG) simply start it.
  106.  
  107.  
  108. How to use Gemterm
  109.  
  110. Gemterm is activated via a click into its menu item, via activating its icon
  111. from the Gemini desktop or via dragging an object onto its Gemini icon. If 
  112. there exists any closed, but still living Gemterm window it will be reopend.
  113. In any other case Gemterm answers with a dialog-box. Now you may define a new 
  114. window. There is no chance of redefining the look of a window once it has been 
  115. created. This should be changed! (If you start Gemterm as PRG you may also
  116. select the menu item "OPEN" to get here). You may configure the following items:
  117.  
  118. - The type of the new window: PROG, PTY, or TTY
  119.  
  120.   PROG means you want to run a TOS program inside the window. That's the 
  121.   normal case (and because of this the default).
  122.  
  123.   PTY means a virtual vt52 terminal connected to a MiNT pty is created 
  124.   with no process inside. You may use it as an output device for a GEM 
  125.   program for example.
  126.   
  127.   TTY means a virtual vt52 terminal connected to "/dev/tty"  is created
  128.   with no process inside. You may use it as a simple terminal program with
  129.   the benefit of cut-and-paste with the local Gemterm-windows. Flow control
  130.   seems not to work correctly! The baud rate and all the other RS232
  131.   parameters have to be set by some other tools, you may probably already
  132.   have. This feature will be extended in the next version of Gemterm (maybe
  133.   with the uw-protocol). If the environment variable "GEMTERMTTY" is defined
  134.   Gemterm will open this device instead of "/dev/tty". So you may connect the
  135.   terminal window to any port you like. (e.g. GEMTERMTTY = "u:/dev/midi"). If
  136.   the value of "GEMTERMTTY" does not denote an existing device, e.g. 
  137.   GEMTERMTTY = "NONE", the TTY feature will be disabled. (This saves one
  138.   file-descriptor for the main application)
  139.  
  140. - The name of the TOS program
  141.  
  142.   A click on the name string will make a file-selector box being opend in
  143.   order to select the TOS or TTP program that will be started inside the
  144.   new window. The default is "U:\bin\sh.ttp" or, if defined, the value of the 
  145.   environment variable "SHELL".
  146.  
  147. - The arguments of the program
  148.  
  149.   Enter any arguments for a TTP program here. They will be passed to the
  150.   program using the standard atari format (no XARG, but the length of the
  151.   string is very limited anyway!).
  152.  
  153. - The current working directory of the program
  154.  
  155.   A click on the current working directory string will make a file-selector
  156.   box being opend in order to select the directory the program will be started
  157.   in. Default is "U:\" or, if defined, the value of the environment variable
  158.   "HOME".
  159.       
  160. - The face and the size of the font for the new window
  161.  
  162.   Select the desired font using the "+" and "-" buttons. A sample of the
  163.   selected font will be displayed.
  164.  
  165. - The lines and columns of the new window
  166.   
  167.   Enter the desired size of the window in terms of characters. There are some
  168.   (sensible ?) lower bounds, but the maximum size is only limited by the
  169.   (staticly) allocated memory for gemterm. Nevertheless a size of 80x25 seems
  170.   to be a VERY sensible default as most of the TOS applications never even
  171.   think of anything else. But if your program understands to use the TERM 
  172.   environment variable and the "/etc/termcap" file you may be able to use
  173.   any size you like. Gemterm itself does not touch the TERM environment 
  174.   variable. It also does not know about a TERMCAP variable.
  175.  
  176. - The length of the history (scroll-back) buffer
  177.  
  178.   Enter the size in terms of KB. The scroll-back buffer contains all the
  179.   lines that scrolled out of the top of the virtual screen. It is a FIFO
  180.   that stores the lines as close as possible. This means e.g. a line
  181.   of four characters only occupies five bytes in the buffer, an empty line
  182.   only one byte. So 4 KB (the default) may be a sensible compromise between
  183.   memory usage and history length. If there is not enough memory left,
  184.   Gemterm will quitely cancel the scroll-back buffer.
  185.   
  186. - The persistent attribute
  187.  
  188.   For each Gemterm window you may define if it is persistent or not. If it is,
  189.   Gemterm tries to reopen it after it has been closed because of a change 
  190.   of the main GEM application (started a new one or left an old one). This may
  191.   cause some problems with GEM applications that are very slow in their
  192.   initialization phase. So disable the persistent attribute, if it makes
  193.   trouble.
  194.  
  195. - The exit-close attribute
  196.  
  197.   For each Gemterm window you may define if should be closed, if the process
  198.   inside exited. (This makes only sense for windows of the PROG type.)
  199.   Otherwise the message "<EXIT>" will be printed by Gemterm into a window
  200.   whose process died.
  201.   
  202. - The "\ -> /" attribute
  203.  
  204.   This attribute specifies if a backslash-to-slash conversion should be done
  205.   during cut-and-paste and Gemini object name insertion. This may be useful
  206.   if the program inside the window expects UX-like pathnames.
  207.  
  208. - The OK-Button creates the defined window.
  209.  
  210. - The SAVE-Button
  211.  
  212.   The current configuration (without the PTY-type windows) will be written
  213.   into the file "U:/etc/gemterm.inf" or, if it is defined, in a file whose name
  214.   is given in the environment variable "GEMTERMINF". Any existing contents 
  215.   of this file will be lost. Gemterm reads this file at its first activation 
  216.   and tries to restore this configuration (including the started processes 
  217.   inside the windows (but not their children!)). The same will happen if you
  218.   select the item "SAVE" from the menu of Gemterm as PRG.
  219.   
  220. Once a Gemterm window is created you may do with it whatever you are used to
  221. do with any GEM window. If you close it via the close box, it will still
  222. exist. If you activate Gemterm again, it will be reopend (if possible). If
  223. you want to destroy an existing Gemterm window press the "Control" key while
  224. clicking on the close box. This will send a "SIGHUP" to the process inside
  225. the window. If you press the "Alt" key instead you will send "SIGKILL". In any
  226. case the window will be destroyed. It can be reused by a new process.
  227.  
  228. Cut-and-paste is done with the mouse buttons. Press the left button to get a
  229. rubberbox to select the text to be cut. Press the right button to insert this
  230. text. The process inside the window will see the input from normal 
  231. "stdin". The cut-and-paste buffer is limited to 512 bytes but this may be
  232. changed by recompiling with a larger constant.
  233.  
  234. Gemterm now also knows about the environment variables "GEMTERMAPPL" and 
  235. "GEMTERMWINS". "GEMTERMAPPL" denotes the main application that
  236. Gemterm wants to talk to via the VA protocol (Gemini is the default). 
  237. "GEMTERMWINS" adjusts the maximum number of term window. This has to be 
  238. configured during startup. There is a trade off between usable windows (ptys) 
  239. and reserved file-descriptors (see also below for the implementation details).
  240.  
  241. A typical setup for Gemterm in the MINT.CNF may look like:
  242.  
  243. setenv GEMTERMINF U:\USER\MFG\GEMTERM.INF
  244. setenv GEMTERMTTY NONE
  245. setenv GEMTERMAPPL GEMINI
  246. setenv GEMTERMWINS 2
  247.  
  248. The TOSRUN pipe has been invented by Eric Smith and his TOSRUN program. Gemterm
  249. now also supports the TOSRUN pipe. It tries to create a pipe called "U:/pipe/
  250. tosrun" and it listens to it. A null-terminated string of the form: 
  251. "<working dir> <program name> <arguments>" written to this pipe will now make 
  252. Gemterm to open a new window with this program started inside. The working dir
  253. and the program name must be given in absolut path-names (including the 
  254. extension ".ttp" or ".tos"). The arguments are optional. All the values given
  255. via the TOSRUN pipe are treaded like changing the corresponding items in the
  256. selector box. This means a comand via the pipe will change the settings of this
  257. box.
  258.  
  259. Gemterm understands an extension of the TOSRUN protocol. If the first char in
  260. a command is 0x01, the second char will be interpreted as a flag set. These
  261. flags have the following meaning:
  262.  
  263. 0x01 Open the selector box before starting the program inside the new window. By
  264.      default the selector box is not displayed.
  265.  
  266. 0x02 Open the new window with the "EXIT_CLOSE" attribute disabled.
  267.  
  268. 0x04 Open the new window with the "EXIT_CLOSE" attribute enabled.
  269.      If neither 0x02 noe 0x04 are set the current default will be used.
  270.  
  271. I can think of a lot of additional settings that should be sensible, but they
  272. are not (yet) implemented.
  273.  
  274. The small programm "gxterm.ttp" (included in the Gemterm distribution) allows 
  275. the easy startup of a new window from within a TOS program. The syntax is:
  276.  
  277. gxterm {-c -k -n} <working dir> <program name> {arguments}
  278.  
  279. The flags c,k, and n correspond to the flags 0x01, 0x02, and 0x04 and all the
  280. other parameters are simply written into the TOSRUN pipe. Now with the call
  281.  
  282. gxterm -n U:\user\mfg\gemterm U:\usr\local\bin\uemacs.ttp gemterm.c
  283.  
  284. a shell script, for example, can open a new editor window that closes when the
  285. editor terminates.
  286.  
  287. ---------------------------------------------------------------------------
  288.  
  289.  
  290. Recompiling Gemterm
  291.  
  292. Gemterm has been compiled with gcc 1.40, but it should compile with any gcc.
  293. Other compilers have not been tested. Gemterm needs a mintlib (currently PL 20)
  294. and some of the headers from the MiNT distribution, namely mintbind.h, signal.h,
  295. and filesys.h. The gemlib from the gcc distribution is also needed.
  296.  
  297. Mint comes with a makefile but recompilation "by hand" is also straight 
  298. forward. There are no special options needed (NO -mshort: ints are 32 bit).
  299.  
  300. ---------------------------------------------------------------------------
  301.  
  302. Some implementation issues
  303.  
  304. Gemterm uses a number of features of MiNT (thank you Eric!). The most 
  305. important extensions used in Gemterm are the multitasking feature and the ptys.
  306.  
  307. Gemterm itself is an ordinary GEM Accessory. It has no additional MiNT process
  308. inside, so its process changes as the GEM main PRG changes. All its resources
  309. are allocated statically (namley the memory and the file-handles). Gemterm
  310. allocates 32 KB of workspace and it uses 4 file-handles for its windows and 
  311. 1 for the "/dev/tty" device. This means there are only 27 handles left 
  312. for the application (this may be a restriction).
  313.  
  314. Gemterm maintains a MiNT pty (or the tty-device) for every window. It starts
  315. the TOS processes with redirected in and out streams and feeds keystrokes into
  316. the pty of the active window. It also polls all windows for output and 
  317. displays it inside the window.
  318.  
  319. Persistent windows are implemented by setting a time-out as reaction to a
  320. AC_CLOSE event. When this time-out expires Gemterm send itself a reopen-
  321. message. (This seems to be compatible to most of the GEM PRGs).
  322.  
  323. ---------------------------------------------------------------------------
  324.  
  325. Compatibility
  326.  
  327. - Gemterm is reported to work on a TT in 16 colors (Gemterm uses only 2).
  328.  
  329. - Gemterm has been running with all kinds of Gdos's (GDOS 1.1, AMCLIGHT, 
  330.   FontGDOS, and FSMGDOS).
  331.  
  332. - Problems have been reported with NVDI (at least older versions).
  333.  
  334. ---------------------------------------------------------------------------
  335.  
  336. Thanks to Scott Kolodzieski for his bug-fixes.
  337.  
  338. ---------------------------------------------------------------------------
  339.  
  340. If you have any ideas, bugreports, ... , drop a mail to:
  341.  
  342. <mfg@gmdzi.gmd.de>
  343.  
  344. Martin Gergeleit
  345. Am Klostergarten 4a
  346. 5300 Bonn 1
  347. Germany
  348.